Detectable Spells v2.01
=======================

John Bytheway
jjb48@cam.ac.uk
2004/05/08

Introduction
============

The detectable spells have been around for a while now, providing improved AI for such purposes as the Ascension mod.  There are, however, some problems with it - primarily that it is wasteful and uses more stats than it needs to in STATS.IDS, thus omitting several spells which might otherwise have been included.

The last version at time of writing, v1.22, also created by myself, is a backwards-compatible version with all the bugs that I had found at the time fixed (although I have since found more bugs).  This version, v2.00, is a significantly changed version, and is not backwards-compatible.  It is for this reason that I have advanced the major version number.

Readmes from the prior versions are included in the Old readmes directory, but note that their contents is obsolete, and not accurate for this version.

Acknowledgements
================

Thanks to all those who have worked on the before - Cirerrek on v1.21, and Vulgar Zildrah and Kensai Ryu on earlier versions.  See the other included readmes for details on their efforts.

Installation
============

Unfortunately, due to a variety of conflicts and a wide range of previous versions the installation is not as simple as it might otherwise be, but it's still not complicated:

1. Copy all files except this one from the main directory into your override directory.

2. If you had a previous version of detectable spells installed, or if you had Ascension installed, then copy the files from the 'Replacement Originals' directory into your override directory.  If you are not sure whether or not you had a previous version installed, then just copy them anyway - it is unlikely to do any harm.

3. If you have Spell50 installed, then copy the files from the 'Spell50' directory into your override directory.

4. If you have Ascension installed, then copy the files from the 'Ascension script replacements' directory (but not the 'source' directory therein) into your override directory.

5. If you wish to compile your own scripts, then copy the new STATS.IDS into your script compiler directory.

I may try to format this as a WeiDU install at some point.

The new SPELLS.IDS
==================

The following is included in the new version of SPELLS.IDS herewith.

156 SCRIPTINGSTATE1                        //Magnet
157 CLERIC_DEATH_WARD
157 SCRIPTINGSTATE2                        //Deathward
158 NEGATIVE_PLANE_PROTECTION
158 SCRIPTINGSTATE3                        //Negative Plane Protection/Barbarian Rage/Minsc Berserk/Boon of Lathander=1
159 RAGE
159 SCRIPTINGSTATE4                        //Kai=1, Quivering Palm=2, Stunning Blow=3, Berserker Enrage=4, Barbarian Rage=5, Minsc Berserk=6
160 CLERIC_BARKSKIN
160 SCRIPTINGSTATE5                        //Barkskin=1
161 SPELL_DEFLECTION                       //Minor Spell Deflection=1, Spell Deflection=2, Shield of the Archons=3
162 WIZARD_SPELL_TURNING                   //Minor Spell Turning=1, Spell Turning=2
163 WIZARD_PROTECTION_FROM_ENERGY
164 WIZARD_SPELL_TRAP                      //Normal Spell Trap=1, Staff of the Magi Spell Trap=2
165 CLERIC_FREE_ACTION
166 PROTECTION_FROM_EVIL                   //Includes innate abilities
167 TRUE_SIGHT                             //Includes innate abilities
168 CLERIC_CHAOTIC_COMMANDS
169 DO_NOT_USE                             //This state cannot be used
170 WIZARD_OTILUKES_RESISLIENT_SPHERE      //Otiluke's Resilient Sphere=1, Protection From Magic scroll=2
171 ACTIVE_COMBAT_DEFENSE                  //Blade barrier=1, Globe of blades=2, Fire Shield (Red)=3, Fire Shield (Blue)=4, Aura of Flaming Death=5
172 CLERIC_PHYSICAL_MIRROR
173 WIZARD_TIME_STOP                       //Normal Time Stop=1, Wish double length Time Stop=2
174 CLERIC_REGENERATION
175 WIZARD_SHIELD
176 WIZARD_PROTECTION_FROM_PETRIFICATION
177 WIZARD_SPELL_SHIELD
178 RESIST_FEAR                            //Resist Fear=1, Remove Fear=2, Invoke Courage=3, Emotion: Hopelessness side effect=4
179 PROTECTION_FROM_MISSILES               //Wizard Protection from Normal Missiles=1, Cleric of Talos Storm Shield=2
180 WIZARD_GREATER_MALISON
181 WIZARD_SPELL_IMMUNITY_ABJURATION
182 WIZARD_TENSERS_TRANSFORMATION
183 WIZARD_PROTECTION_FROM_MAGIC_ENERGY
184 WIZARD_MISLEAD
185 WIZARD_PROTECTION_FROM_WEAPONS         //Normal Weapons=1, Mantle=2, Impr. Mantle=3, Abs. Immunity=4, Magic Weapons=5
186 WIZARD_SPELL_IMMUNITY                  //Conjuration=2, Divination=3, Enchantment=4, Illusion=5, Evocation=6, Necromancy=7, Alteration=8
187 WIZARD_PROTECTION_FROM_THE_ELEMENTS

Comments on the changes
=======================

(For more detailed discussion see the posts to the yahoo group IEEAIS in the month of August 2003).

In this alteration some of the things (I think the only things) that we have lost the ability to detect are the various Wizard armour spells, Creeping Doom and Insect Plague.

I removed the Wizard Armour spells because they are not really too critical.  From the point of view of the caster, they are rarely useful, and you can even use ARMOURCLASS to determine whether it is worth casting them (although only if you know what additional armour class bonuses you are receiving), and since they are generally cast in non-combat situations a timer works well.  From the point of view of an enemy, they only really matter insofar as they affect armour class, and that can be detected seperately.  It would be nice to know when you could remove them, but not nice enough to bother including them.

Both Creeping Doom and Insect Plague can be detected fairly well by checks against casting failure, and you can also (with this installed) eliminate the Protection from Magic Scroll as the source of the spell failure.  That is the only form of spell failure which cannot be dispelled.

The activations for the first three states were put in by Bioware, so I won't change them or add to them (even though I really really want to).

I've added nicer names for SCRIPTINGSTATE2, 3, 4, 5 to improve script readability.  I'm not entirely sure why these less readable names were left in, but I won't remove them in case it's important, and they help with backwards-compatibility too..

I've split Spell Immunity: Abjuration away from the others to prevent it being cloaked by multiple castings.  I guess that if two Spell Immunities are cast then one of them is likely to be Abjuration (that is certainly the case in every enemy AI script I have ever seen which casts any of the Spell Immunities).

I checked STATE_BERSERK and stats CHECKFORBERSERK, BERSERKSTAGE1, BERSERKSTAGE2 in the hope that SCRIPTINGSTATE4 could be put to bettter purpose.  None of these register on the Barbarian or Berserker abilities, and on Minsc's only STATE_BERSERK does.  I suspect STATE_BERSERK refers to the uncontrollability more than anything else, and probably also registers on Morale failure: Berserk, so it's not very useful for checking for the immunities the berserk states confer.  I've redused  the time on the berserker enrage stat so that it no longer includes the winded state - this stat is primarily for enemies checking if you're immune to Maze, etc, not checking whether you can reinstate Berserk (which you can do by using this stat in conjunction with a timer).

I abandoned state 169 since when that is set on any PC (and probably on any other creature too) it makes their feet circle vanish which makes them untargetable.

Advice to scripters
===================

You can use the detectable spells by checking as you would for any other stat.  For example, if you want to check whether a target is vulnerable to your +5 weapon, use CheckStatLT(LastSeenBy(Myself), 4, WIZARD_PROTECTION_FROM_WEAPONS).

The most important thing is to understand the limitations of the detectable spells.  The most significant limitation is due to the sharing of stats by multiple spells.  If more than one of these spells is cast on a single target then only the most recently cast one will register.  However, if the most recent one expires then the stat will revert to the value for the most recently cast spell which is still in effect.

You can use the included spell SPDETECT.SPL to reset all the values to 0, which might be a good idea when using a savegame from before detectable spells were installed, or ones in which you have been using older versions of the detectable spells, since some problems have been reported in those circumstances.

In particular, with old save games, I've noticed false positive returns on 186 WIZARD_SPELL_IMMUNITY value 1 for Player1 (I guess this state is set on Player1 at some point in the game), so you should probably check for general immunity with CheckStatGT(..., 1, WIZARD_SPELL_IMMUNITY), rather than CheckStatGT(..., 0, WIZARD_SPELL_IMMUNITY).  Note also that you must check for Spell Immunity: Abjuration seperately.

Since starting this version I've also noticed erroneous detections of TRUE_SIGHT and ACTIVE_COMBAT_DEFENSE Fire Shield (Blue).  Although I can attribute the former to a mistake in the original detectable spells which set the TRUE_SIGHT state on all targets of True Sight (Permanently!) as well as on the caster, I have no explanation for the latter.  I guess that this is more of a problem than I anticipated, but it only seems to apply to player-made charachters, and mostly only Player1, not the in-game NPCs. To help prevent this being such a big problem you could check for stats being equal to one, where possible, rather than checking for greater than 0.  That does give forwards-compatibility problems, of course, so you might not want to.

Time Stop does not include the Time Stop Trap effect, and Otiluke's sphere probably doesn't include the trap with that effect..

I have noticed that at some times CheckStat(..., 0, ...) does not give the same results as !CheckStatGT(..., 0, ...), and that the latter seems more reliable, so I suggest that you use the latter form rather than the former.

Bear in mind that the Staff of the Magi Spell Trap effect cannot be removed by any means except by using it up (although the next version of Baldurdash promises to fix this), so when testing for spell protection removal use CheckStat(..., 1, WIZARD_SPELL_TRAP), not CheckStatGT(..., 0, WIZARD_SPELL_TRAP).

Advice to those wishing to expand or alter this mod
===================================================

These were the main problems I encountered whilst developing this:

Firstly, incorrect values in the field which is currently listed in NI as 'Unknown' within the Modify Script State effect would make the modifcation not work.  I have been unable to determine what this unknown field represents, although I did locate one instance which was 'SPCL152', as well as others which were certainly not filenames.  Just try copy/pasting different values in until one works.  The most reliable value was 00 00 00 a0 8c 40 00 05.  In retrospect, I don't think that these problems were actually as serious as the others below, and I may have been imagining that these alterations fixed anything.

Secondly, with some spells I was getting messages when they were cat of 'You cannot cast multiple instances of the same contingency spell on yourself'.  This is caused in a spell like Aura of Flaming Death or the Fire Shields with a 'Cast spell on condition' effect, when that effect is not the last effect in the spell ability.  You must insert the 'Modify script state' effect before it.

Thirdly, the ordering of the effects is important in some cases, because the effects are applied in the order they are defined and some prevent later ones from applying.  For example, in Otiluke's Resilient Sphere there is an effect setting magic resistance to 100%.  None of the effects after this one have any effect at all, because they are all resisted (Note that whenever you cast this spell on anyone you always see a 'Magic Resistance' message).  Thus I had to insert the scripting state modification before this.  Similarly, in Greater Malison, there is an effect which confers immunity to Greater Malison (to prevent stacking multiple castings), but this blocks any effects thereafter, because the later effects also come from the spell Greater Malison, to which the recipient is now immune.  This one had me stumped for a long time before I figured it out.

Fourthly, I sometimes didn't get the targeting aspects correct.  You must ensure that your script state modifying effect is affecting the correct target, has the correct Dispel/Resistance and Power properties, and has the correct save type and modifier.

If you wish to make detectable some innate spell cast by some enemy creature you have created or are writing a new script for, then I suggest you use SCRIPTINGSTATE1 for this.  Ascension does this for some of Mellisan's and Balthazar's special innate abilities and it seems to work without problems.

Known Bugs
==========

Mazzy's Invoke Courage also causes 166 PROTECTION_FROM_EVIL to be set to value 1.  Why, I have no idea.

Complete list of files included
===============================

In the main directory
---------------------

Detectable Spells v200 readme.txt - This file, the readme.
STATS.IDS - The new version of STATS.IDS which needs to go in your script compiler directory, and probably your override directory too.
SPCL144.SPL - Kai
SPCL152.SPL - Barbarian Rage
SPCL213.SPL - Protection From Evil
SPCL232.SPL - True Sight
SPCL321.SPL - Enrage
SPCL721.SPL - Storm Shield (Talos)
SPCL732.SPL - True Sight
SPCL811.SPL - Stunning Blow
SPCL820.SPL - Quivering Palm

SPIN117.SPL - Berserk (Minsc)
SPIN121.SPL - Protection From Evil
SPIN676.SPL - Invoke Courage (Mazzy)
SPIN684.SPL - True Sight
SPIN686.SPL - Protection From Magical Weapons (I'm not sure who uses this)
SPIN710.SPL - Spell Deflection (I'm not sure who uses this)
SPIN920.SPL - Spell Turning (I'm not sure who uses this)

SPPR107.SPL - Protecction From Evil
SPPR108.SPL - Remove Fear
SPPR202.SPL - Barkskin
SPPR403.SPL - Free Action
SPPR408.SPL - Protection From Evil 10' Radius
SPPR505.SPL - True Seeing
SPPR508.SPL - Chaotic Commands
SPPR603.SPL - Blade Barrier
SPPR613.SPL - Physical Mirror
SPPR698.SPL - Blade Barrier (I'm not sure if/where this is used)
SPPR701.SPL - Shield of the Archons
SPPR711.SPL - Regeneration
SPPR725.SPL - Globe of Blades
SPPR730.SPL - Aura of Flaming Death

SPWI108.SPL - Protection From Petrification
SPWI113.SPL - Protection From Evil
SPWI114.SPL - Shield
SPWI210.SPL - Resist Fear
SPWI311.SPL - Protection From Normal Missiles
SPWI318.SPL - Minor Spell Deflection
SPWI403.SPL - Fire Shield (Blue)
SPWI411.SPL - Emotion
SPWI412.SPL - Greater Malison
SPWI413.SPL - Otiluke's Resilient Sphere
SPWI418.SPL - Fire Shield (Red)
SPWI511.SPL - Protection From Normal Weapons
SPWI519.SPL - Spell Shield
SPWI522.SPL - Minor Spell Turning
SPWI590-7.SPL - Immunity: <Various>
SPWI603.SPL - Tenser's Transformation
SPWI606.SPL - Protection From Magic Energy
SPWI607.SPL - Mislead
SPWI609.SPL - True Sight
SPWI611.SPL - Protection From Magical Weapons
SPWI618.SPL - Spell Deflection
SPWI701.SPL - Spell Turning
SPWI702.SPL - Protection From the Elements
SPWI708.SPL - Mantle
SPWI802.SPL - Spell Deflection (I'm not sure if/where this is used)
SPWI803.SPL - Protection from Energy
SPWI808.SPL - Improved Mantle
SPWI902.SPL - Spell Trap
SPWI907.SPL - Absolute Immunity
SPWI909.SPL - Time Stop

SPWISH17.SPL - Double length Time Stop/Improved Alacrity

SCRL07.ITM - Protection From Magic (Scroll)
STAF11.ITM - Staff of the Magi

In Ascension script replacements
--------------------------------

A selection of rewritten scripts for the Ascension finale enemies.  The source for these scripts can be found in the Source directory within this directory.

In Examples
-----------

Mages.zip - A WeiDU format mod which improves the performance of spell casters in the game by making use of the detectable spells.  This is loosely based upon the Smarter Mages component of the Tactics mod, and is incompatible with that component, so please unistall one before installing the other.  For more details of what behavious the script induces, please see the comments in the source files for the script in the src folder.  I have played through the first two and a half chapters of SoA with this installed with no problems, but I don't guarantee that problems will not appear later.

In Misc
-------

SPDETECT.SPL - a spell which will reset all the stats used to 0 on all within range.  This may be of use on old charachters from before detectable spells, and I have used it myself without problems.  Note that this is not the same as the version available on IEEAIS, which doesn't work properly because the duration is set to Instant/Limited rather than Instant/Permanent.  Be aware that this will leave permanent effects on your charachters in the save game, but that shouldn't matter.
SPDETECT.ITM - an item you can use to cast the above spell on your party - it looks like the Ring of Gaxx, just put it on and use the item ability with the infravision symbol.
STATS.IDS - A version of STATS.IDS with the comments in, as above.  You can use this if your compiler can cope with commented IDS files (NI cannot).
STATS2.BS/.BAF - A PC script which will display strings for each possible detectable spell, for testing purposes, in compiled and source form.

In Old readmes
--------------

Detectable Spell Files v1.20.rtf - readme from v1.20
Detectable Spells V121 ReadMe.txt - readme from v1.21
DetectableSpells122.txt - readme from v1.22

In Replacement Originals
------------------------

These files are ones which used to be detectable, but are not any more.  If you had an old version of detectable spells installed before you installed this version, then use these to replace the old versions, otherwise lots of detections will not work correctly.

Those marked Original are simply the default versions, so you could delete the existing copies in your override directory if you wish, rather than copying in these versions.

If you have detectable Whirlwind installed, that is likely to cause problems too.

SPCL321D - Enrage (winded period) (Original version)
SPCL741 - Boon of Lathander (Baldurdash version)
SPCL900 - Whirlwind Attack (Original version)***
SPCL901 - Greater Whirlwind Attack (Original version)***

SPPR509 - Magic Resistance (Original)
SPPR517 - Insect Plague (Original)
SPPR717 - Creeping Doom (Original)
SPPR950 - True Sight (Original)*

SPWI102 - Armor (Original)
SPWI317 - Ghost Armor (Original)
SPWI414 - Spirit Armor (Original)
SPWI613 - Improved Haste (Original)**
SPWI921 - Imporved Alacrity (Original)

*This is actually just a true sight effect, it is applied to the targets, not the caster.  In previous versions of detectable spells, this was included with a script state modification, which meant that all targets of a true sight had the true sight state set!  Whoops.
**This was only detectable in versions prior to v1.20
***This was not present in the official detectable spells, but it was included and detectable with Ascension

In Spell50
----------

A variety of the above spells, extended to level 50.

The detectable ones:

SPCL721.SPL - Storm Shield (Talos)

SPPR107.SPL - Protecction From Evil
SPPR202.SPL - Barkskin
SPPR403.SPL - Free Action
SPPR408.SPL - Protection From Evil 10' Radius
SPPR508.SPL - Chaotic Commands
SPPR701.SPL - Shield of the Archons
SPPR711.SPL - Regeneration
SPPR730.SPL - Aura of Flaming Death

SPWI113.SPL - Protection From Evil
SPWI318.SPL - Minor Spell Deflection
SPWI403.SPL - Fire Shield (Blue)
SPWI411.SPL - Emotion
SPWI412.SPL - Greater Malison
SPWI418.SPL - Fire Shield (Red)
SPWI511.SPL - Protection From Normal Weapons
SPWI522.SPL - Minor Spell Turning
SPWI590-7.SPL - Immunity: <Various>
SPWI603.SPL - Tenser's Transformation
SPWI606.SPL - Protection From Magic Energy
SPWI607.SPL - Mislead
SPWI618.SPL - Spell Deflection
SPWI701.SPL - Spell Turning
SPWI702.SPL - Protection From the Elements
SPWI803.SPL - Protection from Energy

And the previously but no longer detectable ones:

SPCL741.SPL - Boon of Lathander
SPPR509.SPL - Magic Resistance
SPWI613.SPL - Improved Haste

Other Notes
===========

SPIN710 and SPIN920 are innate spell deflection and turning.  SPIN920 only turns up to level 4, so is included as Minor Spell Turning.  SPIN710 defelcts up to level 9, so is included as Spell Deflection.  I'm not sure who uses these, if anyone.

Not all the effects of Otiluke's Resilient Sphere last the same amount of time - some last 45, and some 60.  I made the scripting state last for 60.

I fixed a host of other minor bugs with some of these spells.  These included, but are not limited to: incorrect THAC0 values for Tenser's Transformation, incorrect numbers of spell levels absorbed in Shield of the Archons, incorrect times for some levels of Protection From Evil, incorrect power values in Spell Immunity: Conjuration.

Some things which might want to be considered for future inclusion, but perhaps some don't matter because they aren't used:

SPCL222 - Remove Fear?
SPCL233 - Another Prot Evil 10' radius?
SPCL912B - Time Stop Trap effect
SPIN633 - True Seeing?
SPIN853, SPWI853 - Otiluke's Resilient Sphere?
SPRA302 - Spell Deflection?
SPRA303 - Protection From Normal Missiles?

All those abilities for Demogorgan, Mellisan, etc.

Version History
===============

v2.01
-----

- Updated example script for better performance.

v2.00
-----

- Major changes from prior versions (See above for details).